راهنمای جامع برای درک و پیکربندی فایل tsconfig.json برای توسعه بهینه تایپاسکریپت، شامل گزینههای پیشرفته کامپایلر و بهترین شیوهها.
پیکربندی تایپاسکریپت: تسلط بر گزینههای کامپایلر TSConfig
فایل tsconfig.json قلب هر پروژه تایپاسکریپت است. این فایل نحوه تبدیل فایلهای .ts شما به جاوااسکریپت توسط کامپایلر تایپاسکریپت (tsc) را تعیین میکند. یک فایل tsconfig.json با پیکربندی مناسب برای حفظ کیفیت کد، اطمینان از سازگاری در محیطهای مختلف و بهینهسازی فرآیند ساخت، حیاتی است. این راهنمای جامع به بررسی عمیق گزینههای پیشرفته tsconfig.json میپردازد و شما را قادر میسازد تا پروژههای تایپاسکریپت خود را برای دستیابی به بالاترین عملکرد و قابلیت نگهداری تنظیم کنید.
درک مبانی: چرا TSConfig اهمیت دارد
قبل از اینکه به گزینههای پیشرفته بپردازیم، بیایید مرور کنیم که چرا tsconfig.json اینقدر مهم است:
- کنترل کامپایل: این فایل مشخص میکند که کدام فایلها باید در پروژه شما گنجانده شوند و چگونه باید کامپایل شوند.
- بررسی نوع (Type Checking): قوانین و دقت بررسی نوع را تعریف میکند و به شما کمک میکند تا خطاها را در مراحل اولیه چرخه توسعه شناسایی کنید.
- کنترل خروجی: نسخه جاوااسکریپت هدف، سیستم ماژول و دایرکتوری خروجی را تعیین میکند.
- یکپارچهسازی با IDE: اطلاعات ارزشمندی را برای IDEها (مانند VS Code، WebStorm و غیره) برای ویژگیهایی مانند تکمیل خودکار کد، برجستهسازی خطاها و بازآرایی کد (refactoring) فراهم میکند.
بدون فایل tsconfig.json، کامپایلر تایپاسکریپت از تنظیمات پیشفرض استفاده میکند که ممکن است برای همه پروژهها مناسب نباشد. این میتواند منجر به رفتار غیرمنتظره، مشکلات سازگاری و تجربه توسعه نامطلوب شود.
ایجاد TSConfig شما: شروع سریع
برای ایجاد یک فایل tsconfig.json، کافی است دستور زیر را در دایرکتوری ریشه پروژه خود اجرا کنید:
tsc --init
این دستور یک فایل tsconfig.json پایه با برخی گزینههای رایج ایجاد میکند. سپس میتوانید این فایل را برای پاسخگویی به نیازهای خاص پروژه خود سفارشی کنید.
گزینههای کلیدی کامپایلر: یک نمای کلی دقیق
فایل tsconfig.json حاوی یک شیء compilerOptions است که در آن کامپایلر تایپاسکریپت را پیکربندی میکنید. بیایید برخی از مهمترین و پرکاربردترین گزینهها را بررسی کنیم:
target
این گزینه نسخه هدف ECMAScript را برای کد جاوااسکریپت کامپایلشده مشخص میکند. این تعیین میکند که کامپایلر از کدام ویژگیهای جاوااسکریپت استفاده کند و سازگاری با محیط هدف (مانند مرورگرها، Node.js) را تضمین میکند. مقادیر رایج شامل ES5، ES6 (ES2015)، ES2017، ES2018، ES2019، ES2020، ES2021، ES2022، ESNext است. استفاده از ESNext جدیدترین ویژگیهای پشتیبانی شده ECMAScript را هدف قرار میدهد.
مثال:
"compilerOptions": {
"target": "ES2020"
}
این پیکربندی به کامپایلر دستور میدهد تا کد جاوااسکریپت سازگار با ECMAScript 2020 تولید کند.
module
این گزینه سیستم ماژول مورد استفاده در کد جاوااسکریپت کامپایلشده را مشخص میکند. مقادیر رایج شامل CommonJS، AMD، System، UMD، ES6 (ES2015)، ES2020 و ESNext است. انتخاب سیستم ماژول به محیط هدف و بارگذارنده ماژول مورد استفاده (مانند Node.js، Webpack، Browserify) بستگی دارد.
مثال:
"compilerOptions": {
"module": "CommonJS"
}
این پیکربندی برای پروژههای Node.js که معمولاً از سیستم ماژول CommonJS استفاده میکنند، مناسب است.
lib
این گزینه مجموعهای از فایلهای کتابخانهای را مشخص میکند که در فرآیند کامپایل گنجانده میشوند. این فایلهای کتابخانهای تعاریف نوع (type definitions) را برای APIهای داخلی جاوااسکریپت و APIهای مرورگر فراهم میکنند. مقادیر رایج شامل ES5، ES6، ES7، DOM، WebWorker، ScriptHost و موارد دیگر است.
مثال:
"compilerOptions": {
"lib": ["ES2020", "DOM"]
}
این پیکربندی شامل تعاریف نوع برای ECMAScript 2020 و DOM API است که برای پروژههای مبتنی بر مرورگر ضروری است.
allowJs
این گزینه به کامپایلر تایپاسکریپت اجازه میدهد تا فایلهای جاوااسکریپت را در کنار فایلهای تایپاسکریپت کامپایل کند. این میتواند هنگام مهاجرت یک پروژه جاوااسکریپت به تایپاسکریپت یا هنگام کار با کدهای جاوااسکریپت موجود مفید باشد.
مثال:
"compilerOptions": {
"allowJs": true
}
با فعال بودن این گزینه، کامپایلر هم فایلهای .ts و هم .js را پردازش میکند.
checkJs
این گزینه بررسی نوع را برای فایلهای جاوااسکریپت فعال میکند. هنگامی که با allowJs ترکیب شود، به تایپاسکریپت اجازه میدهد تا خطاهای نوع بالقوه را در کد جاوااسکریپت شما شناسایی کند.
مثال:
"compilerOptions": {
"allowJs": true,
"checkJs": true
}
این پیکربندی بررسی نوع را هم برای فایلهای تایپاسکریپت و هم جاوااسکریپت فراهم میکند.
jsx
این گزینه نحوه تبدیل سینتکس JSX (که در React و سایر فریمورکها استفاده میشود) را مشخص میکند. مقادیر رایج شامل preserve، react، react-native و react-jsx است. preserve سینتکس JSX را به همان شکل باقی میگذارد، react آن را به فراخوانیهای React.createElement تبدیل میکند، react-native برای توسعه React Native است، و react-jsx آن را به توابع فکتوری JSX تبدیل میکند. react-jsxdev برای اهداف توسعه است.
مثال:
"compilerOptions": {
"jsx": "react"
}
این پیکربندی برای پروژههای React مناسب است و JSX را به فراخوانیهای React.createElement تبدیل میکند.
declaration
این گزینه فایلهای اعلان (.d.ts) را برای کد تایپاسکریپت شما تولید میکند. فایلهای اعلان اطلاعات نوع را برای کد شما فراهم میکنند و به پروژههای دیگر تایپاسکریپت یا جاوااسکریپت اجازه میدهند تا از کد شما با بررسی نوع مناسب استفاده کنند.
مثال:
"compilerOptions": {
"declaration": true
}
این پیکربندی فایلهای .d.ts را در کنار فایلهای جاوااسکریپت کامپایلشده تولید میکند.
declarationMap
این گزینه فایلهای سورس مپ (.d.ts.map) را برای فایلهای اعلان تولید شده ایجاد میکند. سورس مپها به دیباگرها و ابزارهای دیگر اجازه میدهند تا هنگام کار با فایلهای اعلان، به کد منبع اصلی تایپاسکریپت بازگردند.
مثال:
"compilerOptions": {
"declaration": true,
"declarationMap": true
}
sourceMap
این گزینه فایلهای سورس مپ (.js.map) را برای کد جاوااسکریپت کامپایلشده تولید میکند. سورس مپها به دیباگرها و ابزارهای دیگر اجازه میدهند تا هنگام دیباگ کردن در مرورگر یا محیطهای دیگر، به کد منبع اصلی تایپاسکریپت بازگردند.
مثال:
"compilerOptions": {
"sourceMap": true
}
outFile
این گزینه تمام فایلهای خروجی را به هم متصل کرده و در یک فایل واحد منتشر میکند. این معمولاً برای بستهبندی کد برای برنامههای مبتنی بر مرورگر استفاده میشود.
مثال:
"compilerOptions": {
"outFile": "dist/bundle.js"
}
outDir
این گزینه دایرکتوری خروجی را برای فایلهای جاوااسکریپت کامپایلشده مشخص میکند. اگر مشخص نشود، کامپایلر فایلهای خروجی را در همان دایرکتوری فایلهای منبع قرار میدهد.
مثال:
"compilerOptions": {
"outDir": "dist"
}
این پیکربندی فایلهای جاوااسکریپت کامپایلشده را در دایرکتوری dist قرار میدهد.
rootDir
این گزینه دایرکتوری ریشه پروژه تایپاسکریپت را مشخص میکند. کامپایلر از این دایرکتوری برای حل نامهای ماژول و تولید مسیرهای فایل خروجی استفاده میکند. این به ویژه برای ساختارهای پیچیده پروژه مفید است.
مثال:
"compilerOptions": {
"rootDir": "src"
}
removeComments
این گزینه کامنتها را از کد جاوااسکریپت کامپایلشده حذف میکند. این میتواند به کاهش حجم فایلهای خروجی کمک کند.
مثال:
"compilerOptions": {
"removeComments": true
}
noEmitOnError
این گزینه از تولید فایلهای جاوااسکریپت توسط کامپایلر در صورت شناسایی هرگونه خطای نوع جلوگیری میکند. این تضمین میکند که فقط کد معتبر تولید میشود.
مثال:
"compilerOptions": {
"noEmitOnError": true
}
strict
این گزینه تمام گزینههای بررسی نوع سختگیرانه را فعال میکند. این برای پروژههای جدید بسیار توصیه میشود زیرا به شناسایی خطاهای بالقوه و اجرای بهترین شیوهها کمک میکند.
مثال:
"compilerOptions": {
"strict": true
}
فعال کردن حالت strict معادل فعال کردن گزینههای زیر است:
noImplicitAnynoImplicitThisalwaysStrictstrictNullChecksstrictFunctionTypesstrictBindCallApplynoImplicitReturnsnoFallthroughCasesInSwitch
esModuleInterop
این گزینه قابلیت همکاری بین ماژولهای CommonJS و ES را فعال میکند. این به شما امکان میدهد ماژولهای CommonJS را در ماژولهای ES وارد کنید و بالعکس.
مثال:
"compilerOptions": {
"esModuleInterop": true
}
forceConsistentCasingInFileNames
این گزینه استفاده از حروف با اندازه یکسان در نام فایلها را اعمال میکند. این برای سازگاری بین پلتفرمها مهم است، زیرا برخی از سیستمعاملها به حروف بزرگ و کوچک حساس هستند در حالی که برخی دیگر نیستند.
مثال:
"compilerOptions": {
"forceConsistentCasingInFileNames": true
}
baseUrl و paths
این گزینهها به شما امکان میدهند تا تفکیک ماژول (module resolution) را پیکربندی کنید. baseUrl دایرکتوری پایه را برای تفکیک نامهای ماژول غیرنسبی مشخص میکند و paths به شما اجازه میدهد تا نامهای مستعار (alias) سفارشی برای ماژولها تعریف کنید.
مثال:
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@components/*": ["src/components/*"],
"@utils/*": ["src/utils/*"]
}
}
این پیکربندی به شما امکان میدهد ماژولها را با استفاده از نامهای مستعار مانند @components/MyComponent و @utils/myFunction وارد کنید.
پیکربندی پیشرفته: فراتر از مبانی
اکنون، بیایید برخی از گزینههای پیشرفته tsconfig.json را بررسی کنیم که میتوانند تجربه توسعه تایپاسکریپت شما را بیشتر بهبود بخشند.
کامپایل افزایشی (Incremental Compilation)
تایپاسکریپت از کامپایل افزایشی پشتیبانی میکند که میتواند به طور قابل توجهی سرعت فرآیند ساخت را برای پروژههای بزرگ افزایش دهد. برای فعال کردن کامپایل افزایشی، گزینه incremental را روی true تنظیم کرده و یک گزینه tsBuildInfoFile را مشخص کنید.
مثال:
"compilerOptions": {
"incremental": true,
"tsBuildInfoFile": ".tsbuildinfo"
}
گزینه tsBuildInfoFile فایلی را مشخص میکند که کامپایلر اطلاعات ساخت را در آن ذخیره میکند. این اطلاعات برای تعیین اینکه کدام فایلها در ساختهای بعدی نیاز به کامپایل مجدد دارند، استفاده میشود.
ارجاعات پروژه (Project References)
ارجاعات پروژه به شما امکان میدهند کد خود را به پروژههای کوچکتر و قابل مدیریتتر تقسیم کنید. این میتواند زمان ساخت و سازماندهی کد را برای پایگاههای کد بزرگ بهبود بخشد. یک تشبیه خوب برای این مفهوم، معماری میکروسرویس است - هر سرویس مستقل است، اما به دیگران در اکوسیستم تکیه میکند.
برای استفاده از ارجاعات پروژه، باید برای هر پروژه یک فایل tsconfig.json جداگانه ایجاد کنید. سپس، در فایل tsconfig.json اصلی، میتوانید پروژههایی را که باید ارجاع داده شوند با استفاده از گزینه references مشخص کنید.
مثال:
{
"compilerOptions": {
...
},
"references": [
{ "path": "./project1" },
{ "path": "./project2" }
]
}
این پیکربندی مشخص میکند که پروژه فعلی به پروژههای واقع در دایرکتوریهای ./project1 و ./project2 وابسته است.
تبدیلکنندههای سفارشی (Custom Transformers)
تبدیلکنندههای سفارشی به شما امکان میدهند خروجی کامپایلر تایپاسکریپت را تغییر دهید. این میتواند برای اهداف مختلفی مانند افزودن تبدیلهای کد سفارشی، حذف کد استفاده نشده یا بهینهسازی خروجی برای محیطهای خاص استفاده شود. آنها معمولاً برای وظایف بینالمللیسازی (i18n) و بومیسازی استفاده میشوند.
برای استفاده از تبدیلکنندههای سفارشی، باید یک فایل جاوااسکریپت جداگانه ایجاد کنید که یک تابع را صادر (export) میکند که توسط کامپایلر فراخوانی میشود. سپس، میتوانید فایل تبدیلکننده را با استفاده از گزینه plugins در فایل tsconfig.json مشخص کنید.
مثال:
{
"compilerOptions": {
...
"plugins": [
{ "transform": "./transformer.js" }
]
}
}
این پیکربندی مشخص میکند که فایل ./transformer.js باید به عنوان یک تبدیلکننده سفارشی استفاده شود.
Files، Include و Exclude
علاوه بر compilerOptions، سایر گزینههای سطح ریشه در tsconfig.json کنترل میکنند که کدام فایلها در فرآیند کامپایل گنجانده شوند:
- files: آرایهای از مسیرهای فایل برای گنجاندن در کامپایل.
- include: آرایهای از الگوهای glob که فایلهای مورد نظر برای گنجاندن را مشخص میکند.
- exclude: آرایهای از الگوهای glob که فایلهای مورد نظر برای حذف را مشخص میکند.
این گزینهها کنترل دقیقی بر روی اینکه کدام فایلها توسط کامپایلر تایپاسکریپت پردازش میشوند، فراهم میکنند. به عنوان مثال، میتوانید فایلهای تست یا کدهای تولید شده را از فرآیند کامپایل حذف کنید.
مثال:
{
"compilerOptions": { ... },
"include": ["src/**/*"],
"exclude": ["node_modules", "dist", "**/*.spec.ts"]
}
این پیکربندی تمام فایلهای موجود در دایرکتوری src و زیرشاخههای آن را شامل میشود، در حالی که فایلهای موجود در دایرکتوریهای node_modules و dist و همچنین هر فایلی با پسوند .spec.ts (که معمولاً برای تستهای واحد استفاده میشود) را حذف میکند.
گزینههای کامپایلر برای سناریوهای خاص
پروژههای مختلف ممکن است برای دستیابی به نتایج بهینه به تنظیمات کامپایلر متفاوتی نیاز داشته باشند. بیایید به چند سناریوی خاص و تنظیمات کامپایلر توصیه شده برای هر کدام نگاهی بیندازیم.
توسعه برنامههای وب
برای توسعه برنامههای وب، معمولاً میخواهید از تنظیمات کامپایلر زیر استفاده کنید:
{
"compilerOptions": {
"target": "ESNext",
"module": "ESNext",
"moduleResolution": "Node",
"jsx": "react-jsx",
"esModuleInterop": true,
"strict": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"sourceMap": true,
"outDir": "dist"
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}
این تنظیمات برای برنامههای وب مدرن با استفاده از React یا سایر فریمورکهای مشابه مناسب است. آنها جدیدترین ویژگیهای ECMAScript را هدف قرار میدهند، از ماژولهای ES استفاده میکنند و بررسی نوع سختگیرانه را فعال میکنند.
توسعه بکاند با Node.js
برای توسعه بکاند با Node.js، معمولاً میخواهید از تنظیمات کامپایلر زیر استفاده کنید:
{
"compilerOptions": {
"target": "ESNext",
"module": "CommonJS",
"esModuleInterop": true,
"strict": true,
"sourceMap": true,
"outDir": "dist",
"resolveJsonModule": true
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}
این تنظیمات برای برنامههای Node.js که از سیستم ماژول CommonJS استفاده میکنند مناسب است. آنها جدیدترین ویژگیهای ECMAScript را هدف قرار میدهند، بررسی نوع سختگیرانه را فعال میکنند و به شما امکان میدهند فایلهای JSON را به عنوان ماژول وارد کنید.
توسعه کتابخانه
برای توسعه کتابخانه، معمولاً میخواهید از تنظیمات کامپایلر زیر استفاده کنید:
{
"compilerOptions": {
"target": "ES5",
"module": "UMD",
"declaration": true,
"declarationMap": true,
"sourceMap": true,
"outDir": "dist",
"strict": true,
"esModuleInterop": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "**/*.spec.ts"]
}
این تنظیمات برای ایجاد کتابخانههایی مناسب است که میتوانند هم در محیط مرورگر و هم در Node.js استفاده شوند. آنها فایلهای اعلان و سورس مپها را برای تجربه توسعهدهنده بهتر تولید میکنند.
بهترین شیوهها برای مدیریت TSConfig
در اینجا چند روش برتر برای مدیریت فایلهای tsconfig.json شما آورده شده است:
- با یک پیکربندی پایه شروع کنید: یک فایل
tsconfig.jsonپایه با تنظیمات مشترک ایجاد کنید و سپس آن را در پروژههای دیگر با استفاده از گزینهextendsگسترش دهید. - از حالت strict استفاده کنید: حالت strict را فعال کنید تا خطاهای بالقوه را شناسایی کرده و بهترین شیوهها را اجرا کنید.
- تفکیک ماژول را پیکربندی کنید: تفکیک ماژول را به درستی پیکربندی کنید تا از خطاهای import جلوگیری کنید.
- از ارجاعات پروژه استفاده کنید: کد خود را با استفاده از ارجاعات پروژه به پروژههای کوچکتر و قابل مدیریتتر تقسیم کنید.
- فایل
tsconfig.jsonخود را بهروز نگه دارید: فایلtsconfig.jsonخود را به طور منظم مرور کرده و با تکامل پروژه آن را بهروز کنید. - فایل
tsconfig.jsonخود را در کنترل نسخه قرار دهید: فایلtsconfig.jsonخود را به همراه سایر کدهای منبع به کنترل نسخه بسپارید. - پیکربندی خود را مستند کنید: کامنتهایی به فایل
tsconfig.jsonخود اضافه کنید تا هدف هر گزینه را توضیح دهید.
نتیجهگیری: تسلط بر پیکربندی تایپاسکریپت
فایل tsconfig.json ابزاری قدرتمند برای پیکربندی کامپایلر تایپاسکریپت و کنترل فرآیند ساخت است. با درک گزینههای موجود و پیروی از بهترین شیوهها، میتوانید پروژههای تایپاسکریپت خود را برای عملکرد، قابلیت نگهداری و سازگاری بهینه تنظیم کنید. این راهنما یک نمای کلی جامع از گزینههای پیشرفته موجود در فایل tsconfig.json ارائه داده است و شما را قادر میسازد تا کنترل کامل بر گردش کار توسعه تایپاسکریپت خود داشته باشید. به یاد داشته باشید که همیشه برای بهروزترین اطلاعات و راهنماییها به مستندات رسمی تایپاسکریپت مراجعه کنید. با تکامل پروژههای شما، درک و استفاده شما از این ابزارهای پیکربندی قدرتمند نیز باید تکامل یابد. کدنویسی خوبی داشته باشید!